---
sidebar_label: Query collections
sidebar_position: 16
description: Manage query collections with the Hasura Metadata API
keywords:
  - hasura
  - docs
  - Metadata API
  - API reference
  - query collection
---

# Metadata API Reference: Query Collections

## Introduction

Group queries using query collections.

Create/rename/drop query collections and add/drop a query to a collection using
the following query types.

:::tip Supported from

The Metadata API is supported for versions `v2.0.0` and above and
replaces the older [schema/Metadata API](/api-reference/schema-metadata-api/index.mdx).

:::

## create_query_collection {#metadata-create-query-collection}

`create_query_collection` is used to define a collection.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "create_query_collection",
      "args": {
          "name": "my_collection",
          "comment": "an optional comment",
          "definition": {
              "queries": [
                  {
                      "name": "query_1",
                      "query": "query { test { id name } }"
                  }
              ]
          }
      }
}
```

:::info Note

The queries in query collections are validated against the schema. So, adding an invalid query would result in inconsistent Metadata error.
As the query collection is used in allowlists and REST endpoints, they are validated as well.

:::

### Args Syntax {#metadata-create-query-collection-syntax}

| Key        | Required | Schema                                                                  | Description                  |
| ---------- | -------- | ----------------------------------------------------------------------- | ---------------------------- |
| name       | true     | [CollectionName](/api-reference/syntax-defs.mdx#collectionname)         | Name of the query collection |
| definition | true     | [CollectionQuery](/api-reference/syntax-defs.mdx#collectionquery) array | List of queries              |
| comment    | false    | text                                                                    | Optional comment             |

## rename_query_collection {#metadata-rename-query-collection}

`rename_query_collection` is used to rename a collection

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "rename_query_collection",
    "args": {
         "name": "my_collection",
         "new_name": "my_new_collection"
     }
}
```

### Args syntax {#metadata-rename-query-collection-syntax}

| Key      | Required | Schema                                                          | Description                                 |
| -------- | -------- | --------------------------------------------------------------- | ------------------------------------------- |
| name     | true     | [CollectionName](/api-reference/syntax-defs.mdx#collectionname) | Name of the query collection to be replaced |
| new_name | true     | [CollectionName](/api-reference/syntax-defs.mdx#collectionname) | New name of the query collection            |

## drop_query_collection {#metadata-drop-query-collection}

`drop_query_collection` is used to drop a collection

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "drop_query_collection",
    "args": {
        "collection": "my_collection",
        "cascade": false
    }
}
```

### Args syntax {#metadata-drop-query-collection-syntax}

| Key        | Required | Schema                                                          | Description                                                                   |
| ---------- | -------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| collection | true     | [CollectionName](/api-reference/syntax-defs.mdx#collectionname) | Name of the query collection                                                  |
| cascade    | true     | boolean                                                         | When set to `true`, the collection (if present) is removed from the allowlist |

## add_query_to_collection {#metadata-add-query-to-collection}

`add_query_to_collection` is used to add a query to a given collection.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "add_query_to_collection",
    "args": {
        "collection_name": "my_collection",
        "query_name": "query_2",
        "query": "query {test {name}}"
    }
}
```

### Args Syntax {#metadata-add-query-to-collection-syntax}

| Key             | Required | Schema                                                          | Description                  |
| --------------- | -------- | --------------------------------------------------------------- | ---------------------------- |
| collection_name | true     | [CollectionName](/api-reference/syntax-defs.mdx#collectionname) | Name of the query collection |
| query_name      | true     | [QueryName](/api-reference/syntax-defs.mdx#queryname)           | Name of the query            |
| query           | true     | text                                                            | The GraphQL query text       |

## drop_query_from_collection {#metadata-drop-query-from-collection}

`drop_query_from_collection` is used to remove a query from a given collection.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "drop_query_from_collection",
    "args": {
        "collection_name": "my_collection",
        "query_name": "query_2"
    }
}
```

### Args Syntax {#metadata-drop-query-from-collection-syntax}

| Key             | Required | Schema                                                          | Description                  |
| --------------- | -------- | --------------------------------------------------------------- | ---------------------------- |
| collection_name | true     | [CollectionName](/api-reference/syntax-defs.mdx#collectionname) | Name of the query collection |
| query_name      | true     | [QueryName](/api-reference/syntax-defs.mdx#queryname)           | Name of the query            |

## add_collection_to_allowlist {#metadata-add-collection-to-allowlist}

`add_collection_to_allowlist` is used to add a collection to the allow-list. It is possible to specify a scope, defaulting to global.

If the given collection already exists in the allowlist regardless of scope, `add_collection_to_allowlist` is a no-op.
To change the scope, use [update_scope_of_collection_in_allowlist](#metadata-update-scope-of-collection-in-allowlist).

If the scope is global, all roles will be able to access the queries present in the query collection:

```http
 POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "add_collection_to_allowlist",
    "args": {
        "collection": "my_collection",
        "scope": {
            "global": true
        }
    }
}
```

If the scope is not global, only the listed roles are allowed to
to access the queries:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "add_collection_to_allowlist",
    "args": {
        "collection": "role_based_query_collection",
        "scope": {
            "global": false,
            "roles": [
              "user",
              "editor"
            ]
        }
    }
}
```

If a query occurs in multiple collections, a role will be allowed to access the query if it is listed for any of the collections.

### Args Syntax {#metadata-add-collection-to-allowlist-syntax}

| Key        | Required | Schema                                                          | Description                                                                                                                                                                                                                                                                                                                                               |
| ---------- | -------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| collection | true     | [CollectionName](/api-reference/syntax-defs.mdx#collectionname) | Name of a query collection to be added to the allow-list                                                                                                                                                                                                                                                                                                  |
| scope      | false    | [AllowlistScope](/api-reference/syntax-defs.mdx#allowlistscope) | Scope of the collection in the allowlist. (default: `{global: true}`) When the scope is global, the query collection's queries will be accessible to all roles. When the scope is non-global, the query collection's queries will be accessible to all of the roles listed in the scope. _(non-global scope supported only in cloud/enterprise versions)_ |

## update_scope_of_collection_in_allowlist {#metadata-update-scope-of-collection-in-allowlist}

`update_scope_of_collection_in_allowlist` is used to add change the
scope of a collection in the allowlist. Its effect is the same as first
dropping the collection from the allowlist using
[drop_collection_from_allowlist](#metadata-drop-collection-from-allowlist), and then adding it with the given
scope using [add_collection_to_allowlist](#metadata-add-collection-to-allowlist).

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "update_scope_of_collection_in_allowlist",
    "args": {
        "collection": "previously_global_query_collection",
        "scope": {
            "global": false,
            "roles": [
               "user",
               "editor"
            ]
        }
    }
}
```

### Args Syntax {#metadata-update-scope-of-collection-in-allowlist-syntax}

| Key        | Required | Schema                                                          | Description                                                                                                                                                                                                                                                                                                                   |
| ---------- | -------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| collection | true     | [CollectionName](/api-reference/syntax-defs.mdx#collectionname) | Name of a query collection to be added to the allow-list                                                                                                                                                                                                                                                                      |
| scope      | true     | [AllowlistScope](/api-reference/syntax-defs.mdx#allowlistscope) | Scope of the collection in the allowlist. When the scope is global, the query collection's queries will be accessible to all roles. When the scope is non-global, the query collection's queries will be accessible to all of the roles listed in the scope. _(non-global scope supported only in cloud/enterprise versions)_ |

## drop_collection_from_allowlist {#metadata-drop-collection-from-allowlist}

`drop_collection_from_allowlist` is used to remove a collection from the allow-list.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "drop_collection_from_allowlist",
    "args": {
        "collection": "my_collection_1"
    }
}
```

### Args Syntax {#metadata-drop-collection-from-allowlist-syntax}

| Key        | Required | Schema                                                          | Description                                                  |
| ---------- | -------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
| collection | true     | [CollectionName](/api-reference/syntax-defs.mdx#collectionname) | Name of a query collection to be removed from the allow-list |
